[Appendix A] PPP Tools
Author: Craig Hunt
Date: 1999-02-04T01:42:23Z

#

| Appendix A |

# A. PPP Tools

Contents:
Dial-Up IP
The PPP Daemon
chat

This appendix is a reference for dip, pppd, and chat. These tools are used to create dial-up IP connection for the Point to Point Protocol (PPP). dip and chat are both scripting languages. Creating a script that initializes the modem, dials the remote server, logs in, and configures the remote server is the biggest task in configuring a PPP connection. Chapter 6, Configuring the Interface , provides examples and tutorial information about all three of the programs covered here. This appendix provides a reference to the programs.

## A.1 Dial-Up IP

dip is a scripting tool designed specifically for creating SLIP and PPP connections. [1] The syntax of the dip command is:

> [1] Serial Line IP (SLIP) predates PPP. Today most serial connections are PPP, which is what this appendix emphasizes.

  dip [`options`] [`scriptfile`]

The dip command is invoked with either an option set or a script file specified, or with both. When `scriptfile` is specified, dip executes the commands contained in the script file to create a point-to-point connection. Examples of scripts and dip are shown in Chapter 6. The `options` valid with script files are:

-v

  Runs dip in verbose mode. In this mode, dip echos each line of the script file as it is executed, and displays enhanced status messages.

-m `mtu`

  Sets the Maximum Transmission Unit (MTU) to the number of bytes specified by `mtu`. The default MTU is 296 bytes.

-p `proto`

  Selects the serial line protocol. Possible values for `proto` are: SLIP, CSLIP, PPP, or TERM.

The other dip command line options are:

-k

  Kills the last dip process you started. You can only kill a process you own, unless of course you're root.

-l `device`

  Identifies that the process to be killed is the one that has locked the specified `device`. This option is only valid when used with the -k option.

-i [`username`]

  Runs dip as a login shell to provide a PPP or SLIP server. The diplogin command is equivalent to dip -i. These two forms of the command are used interchangeably, but diplogin is the most common form. diplogin is placed in the login shell field of the /etc/passwd file entry for each PPP client. From there it is run by login. The username from the /etc/passwd file is used to retrieve additional configuration information from /etc/diphosts. If the optional `username` is specified with the diplogin command, that username is used to retrieve the information from the /etc/diphosts file. Chapter 6 provides a tutorial and examples of running diplogin to create a PPP server, and of using the /etc/diphosts file.

-a

  Prompts for the username and password. The -a option is valid only when used with the -i option. The diplogini command is equivalent to dip -i -a. diplogini is used as a login shell in the /etc/passwd file where it is run by login. Runs dip in test mode, which allows you to input individual script language commands directly from the keyboard. The -t option is frequently used in combination with -v so that the result of each command can be better observed. As shown in Chapter 6, this option is used to debug a dip script.

diplogin and diplogini are used only on servers and are not used with a script file. The script file is used on the PPP clients when dip is configured to dial into a remote server. The script file contains the instructions used to do this.

### A.1.1 The dip Script File

The script file is made up of comments, labels, variables, and commands. Any line that begins with a sharp sign (#) is a comment. A label is a line that contains only a string ending in a colon. Labels are used to divide the script into separate procedures. For example, the section of the script that dials the remote host might begin with the label:

>     Dial-in:

A variable stores a value. A variable name is a string that begins with a dollar sign ($). You might, for example, create a variable to hold a loop counter and give it the name $loopcntr. It is possible to create your own variables, but this is rarely done. The variables that are used in most scripts are the special variables defined by dip. Table 13.1 lists the special variables and the value that each holds.

Table A.1: dip Special Variables
Variable | Value Stored
--- | ---
$errlvl | The return code of the last command
$locip | The IP address of the local host
$local | The fully qualified domain name of the local host
$rmtip | The IP address of the remote host
$remote | The fully qualified domain name of the remote host
$mtu | The Maximum Transmission Unit in bytes
$modem | The modem type; currently this must be HAYES
$port | The name of the serial device, e.g., cua0
$speed | The transmission speed of the port

The final component of the script file is the command list. There are many script commands. Because this appendix is a reference, we cover them all. However, most scripts are built using only a few of these commands. See the sample scripts in Chapter 6 and at the end of this section for realistic dip scripts. The complete list of script commands is:

beep [`n`]

  Tells the system to beep the user. Repeat `n` times.

bootp

  Tells the system to use the BOOTP protocol to obtain the local and remote IP addresses. This command applies only to SLIP. PPP has its own protocol for assigning addresses; SLIP does not. Usually SLIP addresses are statically set inside the script. However, some SLIP servers have evolved techniques for dynamic address assignment. The most common method is for the server to display the address as clear text immediately after the connection is made. Use the get $locip remote command to retrieve the address from this type of SLIP server. Other SLIP servers require you to send them a command before they will display the address. Put the required server command in the script and follow it with the get command. Finally, a few SLIP servers use BOOTP to distribute addresses. Use the bootp command in your script to enable BOOTP when it is required by your SLIP server. Sends a BREAK. Some remote servers may require a BREAK as an attention character.

chatkey `keyword code`

  Maps a modem response `keyword` to a numeric `code`. The predefined mappings are:

  > 0 OK
  > 1 CONNECT
  > 2 ERROR
  > 3 BUSY
  > 4 NO CARRIER
  > 5 NO DIALTONE

config [interface|routing] [pre|up|down|post] `arguments...`

  Modifies interface characteristics (interface) or the routing table (routing) either before (pre) the link comes up, when it is up, when it goes down, or after (post) the link is shutdown. For example:

  >     config up routing add canary gw ibis

  adds a route to canary using ibis as the gateway when the link is up. Allowing users to modify the routing table or interface characteristics is very dangerous. The config command is disabled in the DIP code and requires re-compilation to be enabled.

databits 7|8

  Sets the number of data bits to 7 or 8. 8 bits is recommended for PPP and SLIP links.

dec `$variable` [`value`]

  Decrements `$variable` by `value`. The default value is 1.

default

  Sets the PPP connection as the default route.

dial `phonenumber` [`timeout`]

  Dials the `phonenumber`. If the remote modem does not answer within `timeout` seconds, the connection aborts. $errlvl is set to a numeric value based on the keyword returned by the local modem. Set chatkey for the keyword to numeric mappings.

echo on|off

  Enables or disables the display of modem commands.

exit [`n`]

  Exits the script, optionally returning the number `n` as the exit status. Clears the input buffer.

get `$variable` [ask | remote [`timeout`]] `value`

  Sets `$variable` to `value`, unless ask or remote is specified. When ask is specified, the user is prompted for the value. When remote is specified, the value is read from the remote machine, optionally waiting `timeout` seconds for the remote system to respond.

goto `label`

  Jumps to the section of the script identified by `label`.

help

  Lists the dip script commands.

if `expr` goto `label`

  A conditional statement that jumps to the section of the script identified by `label` if the `expression` evaluates to true. The expression must compare a variable to a constant using one of these operators: == (equal), != (not equal), < (less than), > (greater than), <= (less than or equal to), >= (greater than or equal to).

inc `$variable` [`value`]

  Increments `$variable` by `value`. The default value is 1.

init `command`

  Sets the command string used to initialize the modem. The default is ATE0 Q0 V1 X1.

mode SLIP|CSLIP|PPP|TERM

  Selects the serial protocol. The default is SLIP.

modem `type`

  Sets the modem type. Ignore this command. The only legal value is HAYES, and that is the default.

netmask `mask`

  Sets the subnet mask.

parity E|O|N

  Sets the parity to even (E), odd (O), or no (N). No parity (N) is recommended for SLIP and PPP links. Prompts the user for the password. Installs a proxy ARP entry for the remote system in the local host's ARP table.

print `$variable`

  Displays the contents of `$variable`.

psend `command`

  Executes `command` through the default shell passing the output to the serial device. The command runs using the user's real UID.

port `device`

  Identifies the serial device, such as cua0, that attaches the modem. Exits the script with a nonzero exit status, aborting the connection. Resets the modem.

send `string`

  Passes `string` to the serial device.

shell `command`

  Executes `command` through the default shell. The command runs using the user's real UID.

skey [`timeout`]

  Waits for an S/Key challenge from the remote terminal server, prompts the user for the secret key, and generates and sends the response. Waits `timeout` seconds for the challenge. If the timer expires, $errlvl is set to 1; otherwise, it is set to 0. S/Key must be compiled into dip.

sleep `time`

  Delays `time` seconds.

speed `bits-per-second`

  Sets the port speed. The default is 38400.

stopbits 1|2

  Sets the number of stop bits to 1 or 2. Enables terminal mode. In terminal mode, keyboard input is passed directly to the serial device.

timeout `time`

  Sets the `time` in seconds that the line is allowed to remain inactive. When this timer expires, the link is closed.

wait `text` [`timeout`]

  Waits `timeout` seconds for the `text` string to arrive from the remote system. If `timeout` is not specified, the script will wait forever.

In the next section we put some of these commands to work in a realistic script.

#### A.1.1.1 A sample dip script

This script is based on the PPP sample from Chapter 6. Labels and error detection have been added to create a more robust script.

>     # Select configuration settings
>     setup:
>     # Ask PPP to provide the addresses
>     get $local 0.0.0.0
>     # Select the port
>     port cua1
>     # Set the port speed
>     speed 57600
>     # Create a loop counter
>     get $loopcntr 0

>     # Dial the remote server
>     dialin:
>     # Reset the modem and clear the input buffer
>     reset
>     flush
>     # Dial the PPP server and check the modem response
>     dial *70,301-555-1234
>     # If BUSY, dial again
>     if $errlvl == 3 goto redial
>     # If some other error, abort
>     if $errlvl != 1 goto dial-error
>     # Otherwise rest loop counter
>     get $loopcntr 0
>     # Give the server 2 seconds to get ready
>     sleep 2

>     # Login to the remote server
>     login:
>     # Send a carriage-return to wake up the server
>     send \r
>     # Wait for the Username> prompt and send the username
>     wait name> 20
>     if $errlvl != 0 goto try-again
>     send kristin\r
>     # Wait for the Password> prompt and send the password
>     wait word> 10
>     if $errlvl != 0 goto server-failure
>     password
>     # Wait for the PPP server's command line prompt
>     wait > 20
>     if $errlvl != 0 goto server-failure
>     # Send the command required by the PPP server
>     send ppp enabled\r

>     # Success! We're on-line
>     connected:
>     # Set the interface to PPP mode
>     mode PPP
>     # Exit the script
>     exit

>     # Error processing routines

>     # Try dialing 3 times.  Wait 5 seconds between attempts
>     redial:
>     inc $loopcntr
>     if $loopcntr > 3 goto busy-failure
>     sleep 5
>     goto dialin

>     # Try a second carriage return
>     try-again:
>     inc $loopcntr
>     if $loopcntr > 1 goto server-failure
>     goto login

>     dial-error:
>     print Dial up of $remote failed.
>     quit

>     server-failure:
>     print $remote failed to respond.
>     quit

>     busy-failure:
>     print $remote is busy.  Try again later.
>     quit

This script provides a realistic example of the commands used in most scripts. However, you may encounter a particularly tough scripting problem. If you do, the abundance of scripting commands available with dip should be able to handle it. If dip can't do the job, try expect. See Exploring Expect by Don Libes (O'Reilly &amp;amp;amp;amp; Associates) for a full description of the expect scripting language.

13.7 Summary |  | A.2 The PPP Daemon